cd <old-server-install-dir>/bin ./rhq-server.bat remove
This page is for upgrading or re-installing an existing RHQ Server. To install a new RHQ Server go to Installing the Server.
RHQ does not support mixed-versions among running components. When upgrading RHQ, all RHQ components upgraded with rhqctl must be brought down and upgraded before returning to service.
This does not include those RHQ Agents prepared for auto-update - those will not need to be shutdown. They will auto-update when they connect to the new servers.
Loss of minimal monitoring data is inevitable given the down-time involved in shutting down instances of the RHQ Agents during the upgrade process. In addition, if you have a resource in inventory corresponding to the RHQ Server itself, upgrading RHQ will entail the loss of all data for that RHQ Server resource.
Perform the following steps prior to your upgrade. The server should still be running until the step instructing to shut it down.
RHQ Agents that were installed with your RHQ Server or RQH Storage Node components (via rhqctl) are not auto-updated and should be shutdown. The available methods to shutdown these agents are the agent wrapper's stop command, the quit prompt command, or the RHQ Agent resource operation; however, the recommended way to shut them down is the rhqctl stop --agent command.
It is most efficient to remove "out of service" platform resources prior to the upgrade. If you have machines you have stopped, decommissioned or will stop monitoring then stop any RHQ Agents that are still running on those machines. Then, via the RHQ GUI, uninventory the platforms that are no longer relevant.
Because the upgrade will replace the RHQ Servers, any currently imported RHQ Server resources will no longer be available after the upgrade. New RHQ Server resources will be discovered and can be subsequently imported.
If, for some reason, you prefer to keep the old RHQ Server resources then ignore this step. They will have DOWN availability after the upgrade but can be uninventoried later, if so desired.
Note that all RHQ Agents installed via rqhctl should already have been stopped.
Stop the RHQ Servers.
If you are running a pre 4.8 RHQ Server (that is, an RHQ Server whose version if 4.7 or earlier) as a Windows service, uninstall the Windows service:
cd <old-server-install-dir>/bin ./rhq-server.bat remove
Stop the RHQ Storage Nodes after the servers are down.
This is only relevant to RHQ 4.8 and later. Note that rhqctl stop will stop all RHQ components previously installed with rhqctl which includes RHQ Server, RHQ Storage Node, and RHQ Agent installations.
Do not stop the RHQ database - ensure it is still running.
Do not delete the existing RHQ Server directory, it is used during the upgrade.
The rhqctl upgrade will merge the old rhq-server.properties into the new rhq-server.properties so you probably will not need to worry about merging them yourself. However, you will probably want to make sure most, if not all, values you had in the old properties file are the same in the new after the upgrade.
In the rare case that you customized the old bin/rhq-server.sh (if on UNIX/Linux) or bin/wrapper/rhq-server-wrapper.conf (if on Windows) files, back them up because you will need to reapply those changes manually.
You should strongly consider backing up your database prior to proceeding. In case problems arise during the database upgrade, having a backup will allow you to restore to your previous state. Not doing so risks a potential loss of all prior data.
Unzip the distribution to the directory within which it will be executed from, e.g.:
cd /opt/rhq unzip rhq-server-4.8.0.zip
The new installation should not be copied on top of a previous installation. It is recommended to unzip to the same parent directory (e.g. /opt/rhq), making it a sibling root directory to the the existing install. All RHQ distribution zip files have a directory structure that ensure their content is extracted into a version-specified directory (e.g. "rhq-server-4.8.0") so this usually isn't a problem unless you are attempting to reinstall the same version as was previously installed. For example, the above commands will create a directory named /opt/rhq/rhq-server-4.8.0
Because the upgrade will merge old settings into the new environment it should not be necessary to alter any properties in the newly unzipped server.
If for some reason you do need to edit rhq-server.properties prior to the upgrade:
Do not set rhq.autoinstall.database to the value of "overwrite" since this will purge all the RHQ data in the database and effectively make this a new, clean install and not a true upgrade. Note that the rhqctl control script will attempt to set this value to "auto" so an overwrite is not mistakenly performed.
Do make sure you set rhq.server.high-availability.name to the original server's name - that is, this should be the same server name of the server you are upgrading. If the previous installed server left this blank, you can leave this blank as well, but you must ensure that the hostname/domain of the machine has not changed. If that did change, you must explicitly put the old name of the server as the value of this property. If this name does not match the previous server's name, you will effectively be adding another server to the RHQ HA Cloud, which is not what you want to do when simply upgrading an already existing server. Again, rhqctl will attempt to merge the old value in the old rhq-server.properties file to the new rhq-server.properties file, so you really should not have to do anything.
If you aren't sure what the name was, you can ask the server installer to give you a list of all existing servers currently registered in the RHQ system. You do this via the --listservers (aka -l) command line option to the rhq-installer script:
<rhq-install-dir>/bin/rhq-installer.[sh,bat] --listservers
The RHQ Server upgrade is performed via the <rhq-install-dir>/bin/rhqctl upgrade command. Please review the command options before continuing.
In particular the --from-server-dir option is required. It specifies the install directory of the RHQ Server you are upgrading from and it is there that settings will be merged. For example, if your old server was installed at /opt/rhq/rhq-server-4.7, you will want to use the option "--from-server-dir /opt/rhq/rhq-server-4.7"
There are some important things to note when upgrading pre RHQ 4.8 servers. In particular, the upgrade will involve the initial installation of an RHQ Storage Node (unless --use-remote-storage-node is specified). And every RHQ Storage Node requires an RHQ Agent to manage it. In addition, if you wish to retain your old measurement data, you will need to run the data migrator tool to transfer the old measurement data from your RDBMS database to the new storage backend.
Starting in RHQ 4.8 the RHQ Agent will be installed for all servers co-located with an RHQ Storage Node, which is the default. The Agent will be installed to a fixed directory, which is the parent directory of the new server installation (making it a sibling directory). The --from-agent-dir option must be specified to maintain a non-default agent location, if it exists. For example, if you are upgrading an older agent located at /home/rhqproject/rhq-agent, you would need to specify the option "--from-agent-dir /home/rhqproject/rhq-agent" in order to upgrade that agent. The new agent will remain in that location.
To alter any defaults for the RHQ Storage Node create a <rhq-install-dir>/bin/rhq-storage.properties file. In this file you can specify any of the RHQ Storage Node --storage-config options. These include the directories for data storage, host and port information, and several other options.
While optional, if you do not run the data migrator tool, all of your old measurement data from the old install will no longer be available. If you wish to retain your historical measurement data, you need to run the data migrator tool. The rhqctl upgrade command provides an option --run-data-migrator. That option gives you things such as: the ability to run the data migration tool as part of the upgrade, or an estimate of how long data migration would take, or the full command you need to use to run the data migration manually, or the ability to skip the data migration all together.
See the RHQ Control Script page for more on this option.
On Windows the RHQ Server, RHQ Storage Node, and RHQ Agent will be installed as Windows Services. See more here before installing.
Because the upgrade may result in new Windows services, it is important to ensure the services will be run as the desired user. Set the required environment variables as needed.
When all of the above steps have been completed the upgrade command can be executed:
cd <new-install-dir>/bin rhqctl upgrade --from-server-dir <old-install-dir> [--from-agent-dir <old-agent-dir>] [options]
This will:
Merge the old RHQ Storage Node settings into the RHQ Storage Node, or install a new RHQ Storage Node, and start the RHQ Storage Node.
Merge the old RHQ Server settings into the new RHQ Server and start the RHQ Server.
Update the old RHQ Agent or install a new RHQ Agent if necessary, and start the RHQ Agent.
During the upgrade you may see error messages similar to the following in the console. These error messages are harmless.
ERROR [ClientCommandSenderTask] {ClientCommandSenderTask.send-failed}Failed to send
command [Command: type=[remotepojo]; cmd-in-response=[false]; config=[{rhq.timeout=1000,
rhq.send-throttle=true}]; params=[{targetInterfaceName=org.rhq.enterprise.communications.Ping,
invocation=NameBasedInvocation[ping]}]]. Cause: org.jboss.remoting.CannotConnectException:[.....]
Upgrade each RHQ Server in your HA installation. If you run only a single RHQ Server you can skip this step.
Follow the Manually Upgrading the Agent instructions if you need to manually upgrade your agents. If your agents will auto-update themselves, you don't have to do anything for this step.
rhqctl upgrade will, by default, start all of the components that were upgraded. For completeness, here is the command you will need to know to restart the components manually. See Running the RHQ Server for more details.
cd <new-install-dir>/bin rhqctl start